/*
 * Copyright (c) 2007, 2013, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package java.nio.channels;

import java.nio.ByteBuffer;
import java.util.concurrent.Future;

/**
 * An asynchronous channel that can read and write bytes.
 *
 * <p> Some channels may not allow more than one read or write to be outstanding
 * at any given time. If a thread invokes a read method before a previous read
 * operation has completed then a {@link ReadPendingException} will be thrown.
 * Similarly, if a write method is invoked before a previous write has completed
 * then {@link WritePendingException} is thrown. Whether or not other kinds of
 * I/O operations may proceed concurrently with a read operation depends upon
 * the type of the channel.
 *
 * <p> Note that {@link java.nio.ByteBuffer ByteBuffers} are not safe for use by
 * multiple concurrent threads. When a read or write operation is initiated then
 * care must be taken to ensure that the buffer is not accessed until the
 * operation completes.
 *
 * @see Channels#newInputStream(AsynchronousByteChannel)
 * @see Channels#newOutputStream(AsynchronousByteChannel)
 *
 * @since 1.7
 */
// 可以读取和写入字节的异步通道。
// 某些通道可能不允许在任何给定时间有多个读取或写入未完成。
// 如果线程在上一个读取操作完成之前调用读取方法，则将抛出ReadPendingException
// 同样，如果在上一次写入完成之前调用 write 方法，则会抛出 WritePendingException 。
// 其他类型的 I/O 操作是否可以与读取操作同时进行取决于通道的类型。
// 请注意， ByteBuffers 多个并发线程使用不安全。
// 启动读取或写入操作时，必须注意确保在操作完成之前不会访问缓冲区。
public interface AsynchronousByteChannel
    extends AsynchronousChannel
{
    /**
     * Reads a sequence of bytes from this channel into the given buffer.
     *
     * <p> This method initiates an asynchronous read operation to read a
     * sequence of bytes from this channel into the given buffer. The {@code
     * handler} parameter is a completion handler that is invoked when the read
     * operation completes (or fails). The result passed to the completion
     * handler is the number of bytes read or {@code -1} if no bytes could be
     * read because the channel has reached end-of-stream.
     *
     * <p> The read operation may read up to <i>r</i> bytes from the channel,
     * where <i>r</i> is the number of bytes remaining in the buffer, that is,
     * {@code dst.remaining()} at the time that the read is attempted. Where
     * <i>r</i> is 0, the read operation completes immediately with a result of
     * {@code 0} without initiating an I/O operation.
     *
     * <p> Suppose that a byte sequence of length <i>n</i> is read, where
     * <tt>0</tt>&nbsp;<tt>&lt;</tt>&nbsp;<i>n</i>&nbsp;<tt>&lt;=</tt>&nbsp;<i>r</i>.
     * This byte sequence will be transferred into the buffer so that the first
     * byte in the sequence is at index <i>p</i> and the last byte is at index
     * <i>p</i>&nbsp;<tt>+</tt>&nbsp;<i>n</i>&nbsp;<tt>-</tt>&nbsp;<tt>1</tt>,
     * where <i>p</i> is the buffer's position at the moment the read is
     * performed. Upon completion the buffer's position will be equal to
     * <i>p</i>&nbsp;<tt>+</tt>&nbsp;<i>n</i>; its limit will not have changed.
     *
     * <p> Buffers are not safe for use by multiple concurrent threads so care
     * should be taken to not access the buffer until the operation has
     * completed.
     *
     * <p> This method may be invoked at any time. Some channel types may not
     * allow more than one read to be outstanding at any given time. If a thread
     * initiates a read operation before a previous read operation has
     * completed then a {@link ReadPendingException} will be thrown.
     *
     * @param   <A>
     *          The type of the attachment
     * @param   dst
     *          The buffer into which bytes are to be transferred
     * @param   attachment
     *          The object to attach to the I/O operation; can be {@code null}
     * @param   handler
     *          The completion handler
     *
     * @throws  IllegalArgumentException
     *          If the buffer is read-only
     * @throws  ReadPendingException
     *          If the channel does not allow more than one read to be outstanding
     *          and a previous read has not completed
     * @throws  ShutdownChannelGroupException
     *          If the channel is associated with a {@link AsynchronousChannelGroup
     *          group} that has terminated
     */
    // 将字节序列从此通道读取到给定缓冲区中。
    // 此方法启动异步读取操作，以将字节序列从此通道读取到给定缓冲区中。
    // 该 handler 参数是在读取操作完成（或失败）时调用的完成处理程序。
    // 传递给完成处理程序的结果是读取的字节数，或者 -1 如果由于通道已到达流末尾而无法读取字节。
    // 读取操作最多可以从通道读取 r 个字节，其中 r 是缓冲区中剩余的字节数，即dst.remaining()尝试读取时。
    // 当 r 为 0 时，读取操作立即完成，结果为 不0启动 I/O 操作。
    // 假设读取长度为 n 的字节序列，其中 0 < n < = r。
    // 此字节序列将被传输到缓冲区中，以便序列中的第一个字节位于索引 p 处，最后一个字节位于索引 p + n - 1 处 ，其中 p 是执行读取时缓冲区的位置。
    // 完成后，缓冲区的位置将等于p + n;它的极限不会改变。
    // 缓冲区对于多个并发线程使用不安全，因此在操作完成之前应注意不要访问缓冲区。
    // 可以随时调用此方法。某些通道类型可能不允许在任何给定时间有多个读取未完成。如果线程在上一个读取操作完成之前启动读取操作，则将抛出ReadPendingException
    // 参数：
    // dst – 要传输到字节的缓冲区 attachment– 要附加到 I/O 操作的对象;null可以 handler – 完成处理程序
    // 抛出：
    // IllegalArgumentException – 如果缓冲区是只读的
    // ReadPendingException – 如果通道不允许多个读取未完成，并且先前的读取尚未完成
    // ShutdownChannelGroupException– 如果通道与已终止的通道相关联group
    <A> void read(ByteBuffer dst,
                  A attachment,
                  CompletionHandler<Integer,? super A> handler);

    /**
     * Reads a sequence of bytes from this channel into the given buffer.
     *
     * <p> This method initiates an asynchronous read operation to read a
     * sequence of bytes from this channel into the given buffer. The method
     * behaves in exactly the same manner as the {@link
     * #read(ByteBuffer,Object,CompletionHandler)
     * read(ByteBuffer,Object,CompletionHandler)} method except that instead
     * of specifying a completion handler, this method returns a {@code Future}
     * representing the pending result. The {@code Future}'s {@link Future#get()
     * get} method returns the number of bytes read or {@code -1} if no bytes
     * could be read because the channel has reached end-of-stream.
     *
     * @param   dst
     *          The buffer into which bytes are to be transferred
     *
     * @return  A Future representing the result of the operation
     *
     * @throws  IllegalArgumentException
     *          If the buffer is read-only
     * @throws  ReadPendingException
     *          If the channel does not allow more than one read to be outstanding
     *          and a previous read has not completed
     */
    // 将字节序列从此通道读取到给定缓冲区中。
    // 此方法启动异步读取操作，以将字节序列从此通道读取到给定缓冲区中。
    // 该方法的行为方式 read(ByteBuffer,Object,CompletionHandler) 与该方法完全相同，只是此方法返回表示挂起结果的Future而不是指定完成处理程序
    // Future' get s 方法返回读取的字节数，或者 -1 如果由于通道已到达流末尾而无法读取字节。
    // 参数：
    // dst – 要传输到字节的缓冲区
    // 返回：
    // 代表操作结果的未来
    // 抛出：
    // IllegalArgumentException – 如果缓冲区是只读的
    // ReadPendingException – 如果通道不允许多个读取未完成，并且先前的读取尚未完成
    Future<Integer> read(ByteBuffer dst);

    /**
     * Writes a sequence of bytes to this channel from the given buffer.
     *
     * <p> This method initiates an asynchronous write operation to write a
     * sequence of bytes to this channel from the given buffer. The {@code
     * handler} parameter is a completion handler that is invoked when the write
     * operation completes (or fails). The result passed to the completion
     * handler is the number of bytes written.
     *
     * <p> The write operation may write up to <i>r</i> bytes to the channel,
     * where <i>r</i> is the number of bytes remaining in the buffer, that is,
     * {@code src.remaining()} at the time that the write is attempted. Where
     * <i>r</i> is 0, the write operation completes immediately with a result of
     * {@code 0} without initiating an I/O operation.
     *
     * <p> Suppose that a byte sequence of length <i>n</i> is written, where
     * <tt>0</tt>&nbsp;<tt>&lt;</tt>&nbsp;<i>n</i>&nbsp;<tt>&lt;=</tt>&nbsp;<i>r</i>.
     * This byte sequence will be transferred from the buffer starting at index
     * <i>p</i>, where <i>p</i> is the buffer's position at the moment the
     * write is performed; the index of the last byte written will be
     * <i>p</i>&nbsp;<tt>+</tt>&nbsp;<i>n</i>&nbsp;<tt>-</tt>&nbsp;<tt>1</tt>.
     * Upon completion the buffer's position will be equal to
     * <i>p</i>&nbsp;<tt>+</tt>&nbsp;<i>n</i>; its limit will not have changed.
     *
     * <p> Buffers are not safe for use by multiple concurrent threads so care
     * should be taken to not access the buffer until the operation has
     * completed.
     *
     * <p> This method may be invoked at any time. Some channel types may not
     * allow more than one write to be outstanding at any given time. If a thread
     * initiates a write operation before a previous write operation has
     * completed then a {@link WritePendingException} will be thrown.
     *
     * @param   <A>
     *          The type of the attachment
     * @param   src
     *          The buffer from which bytes are to be retrieved
     * @param   attachment
     *          The object to attach to the I/O operation; can be {@code null}
     * @param   handler
     *          The completion handler object
     *
     * @throws  WritePendingException
     *          If the channel does not allow more than one write to be outstanding
     *          and a previous write has not completed
     * @throws  ShutdownChannelGroupException
     *          If the channel is associated with a {@link AsynchronousChannelGroup
     *          group} that has terminated
     */
    // 将字节序列从给定缓冲区写入此通道。
    // 此方法启动异步写入操作，以将字节序列从给定缓冲区写入此通道。
    // 该 handler 参数是在写入操作完成（或失败）时调用的完成处理程序。
    // 传递给完成处理程序的结果是写入的字节数。
    // 写入操作最多可以向通道写入 r 个字节，其中 r 是缓冲区中剩余的字节数，即src.remaining()尝试写入时。
    // 其中 r 为 0，写入操作立即完成，结果为 不0启动 I/O 操作。
    // 假设写入一个长度为 n 的字节序列，其中 0 < n < = r。
    // 此字节序列将从索引 p 开始从缓冲区传输，其中 p 是执行写入时缓冲区的位置;
    // 写入的最后一个字节的索引将为 p + n - 1。完成后，缓冲区的位置将等于p + n;它的极限不会改变。
    // 缓冲区对于多个并发线程使用不安全，因此在操作完成之前应注意不要访问缓冲区。
    // 可以随时调用此方法。某些通道类型可能不允许在任何给定时间有多个未完成的写入。
    // 如果线程在上一个写入操作完成之前启动写入操作，则将抛出 。WritePendingException
    // 参数：
    // src – 要从中检索字节的缓冲区
    // attachment– 要附加到 I/O 操作的对象;null可以
    // handler – 完成处理程序对象
    // 抛出：
    // WritePendingException – 如果通道不允许多个写入未完成，并且之前的写入尚未完成
    // ShutdownChannelGroupException– 如果通道与已终止的通道相关联group
    <A> void write(ByteBuffer src,
                   A attachment,
                   CompletionHandler<Integer,? super A> handler);

    /**
     * Writes a sequence of bytes to this channel from the given buffer.
     *
     * <p> This method initiates an asynchronous write operation to write a
     * sequence of bytes to this channel from the given buffer. The method
     * behaves in exactly the same manner as the {@link
     * #write(ByteBuffer,Object,CompletionHandler)
     * write(ByteBuffer,Object,CompletionHandler)} method except that instead
     * of specifying a completion handler, this method returns a {@code Future}
     * representing the pending result. The {@code Future}'s {@link Future#get()
     * get} method returns the number of bytes written.
     *
     *
     * @param   src
     *          The buffer from which bytes are to be retrieved
     *
     * @return A Future representing the result of the operation
     *
     * @throws  WritePendingException
     *          If the channel does not allow more than one write to be outstanding
     *          and a previous write has not completed
     */
    // 将指定的缓存区中的字节序列写入到此Channel
    // 此方法启动异步写入操作，以将字节序列从给定缓冲区写入此通道。
    // 该方法的行为方式 write(ByteBuffer,Object,CompletionHandler) 与该方法完全相同，只是此方法返回表示挂起结果的 Future 而不是指定完成处理程序。
    // Future的方法 get 返回写入的字节数。
    // 参数：
    // src – 要从中检索字节的缓冲区
    // 返回：
    // 代表操作结果的未来
    Future<Integer> write(ByteBuffer src);
}
